home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / Implementation / Storage / Bento / CM / ListMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-02-13  |  10.3 KB  |  300 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        ListMgr.h
  3.  
  4.     Contains:    Container Manager Doubly Linked Lists Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1991-1994 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     8/26/94    EL        #1181622 Ownership update.
  15.  
  16.     To Do:
  17. */
  18.  
  19. /*---------------------------------------------------------------------------*
  20.  |                                                                           |
  21.  |                             <<< ListMgr.h >>>                             |
  22.  |                                                                           |
  23.  |              Container Manager Doubly Linked Lists Interfaces             |
  24.  |                                                                           |
  25.  |                               Ira L. Ruben                                |
  26.  |                                 11/26/91                                  |
  27.  |                                                                           |
  28.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  29.  |                           All rights reserved.                            |
  30.  |                                                                           |
  31.  *---------------------------------------------------------------------------*
  32.  
  33.  The ListMgr package contains all the generic doubly linked list routines. The routines are
  34.  the low level generic doubly linked list manipulators which the higher level "glue"
  35.  routines use.
  36.  
  37.  All structs list cells that are to be maintained as doubly linked lists with this package
  38.  must be of the form:
  39.  
  40.                  struct {
  41.                     ListLinksPtr theLinks;
  42.                     ...
  43.                 }...;
  44.                 
  45.  In other words, a field (any name will do) of type ListLinksPtr MUST be the first field
  46.  of the struct.  The caller allocates all the struct list cells.  This package enters
  47.  them into a list based whose head and tail are pointed to by a header which takes the
  48.  following form:
  49.  
  50.                  struct {
  51.                     ListHdr theListHeader;
  52.                     ...
  53.                 }...;
  54.  
  55.  This is similar to the list entries themselves.  Here a ListHdr is the first field of
  56.  some structure.  Note, it is NOT necessary to make the ListHdr the first entry of a
  57.  larger structure if you pass the pointer to ListHdr pointer explicitly as the list
  58.  header pointer to any of the list routines defined here.
  59.  
  60.  Being a generic package the links and the header have to be at a know place in otherwise
  61.  arbitrary structs.  Hence the position requirements.
  62. */
  63.  
  64.  
  65. #ifndef __LISTMGR__
  66. #define __LISTMGR__
  67.  
  68. #ifndef __CM_API_TYPES__
  69. #include "CMAPITyp.h"
  70. #endif
  71.  
  72. struct SessionGlobalData;
  73.  
  74.                                                                     CM_CFUNCTIONS
  75.  
  76. struct ListLinks {                                                    /* must be the first field in any list entry */
  77.     struct ListLinks *next, *prev;                        /*        next/previous list links                             */
  78. };
  79. typedef struct ListLinks ListLinks, *ListLinksPtr;
  80.  
  81. struct ListHdr {                                                        /* all list headers must look like this            */
  82.     ListLinksPtr     head, tail;                                    /*         head/tail of the list                                    */
  83.     CM_ULONG        nbrOfCells;                                    /*        number of cells on the list                        */
  84. };                                                                                    /* struct can be 1st thin in a larger struct*/
  85. typedef struct ListHdr ListHdr, *ListHdrPtr;
  86.  
  87. #ifndef LISTMACROS                                                    
  88. #define LISTMACROS 1                                                /* 0 for less optimum function calls                */
  89. #endif
  90.  
  91.  
  92. void *cmInitList(const void *theList);
  93.     /*
  94.     This routine takes a list header and initializes the head and tail pointers to NULL.  All
  95.     empty lists are assumed to have NULL head and tail pointers.  The function returns the
  96.     input header pointer as its result.
  97.     */
  98.     
  99.     
  100. void *cmInsertBeforeListCell(const void *theList, const void *theCell, const void *beforeThisCell);
  101.     /*
  102.     Given a pointer to a list header (theList), this routine inserts a new cell (theCell)
  103.     before another cell already on the list (beforeThisCell).  The function returns the
  104.     input inserted cell pointer as its result.
  105.     
  106.     If beforeThisCell is NULL this function inserts theCell at the beginning of the list.
  107.     
  108.     If theCell is NULL, nothing is done and NULL is returned.
  109.     */
  110.     
  111.     
  112. void *cmInsertAfterListCell(const void *theList, const void *theCell, const void *afterThisCell);
  113.     /*
  114.     Given a pointer to a list header (theList), this routine inserts a new cell (theCell)
  115.     after another cell already on the list (beforeThisCell).  The function returns the
  116.     input inserted cell pointer as its result.
  117.     
  118.     If afterThisCell is NULL this function appends theCell to the end of the list.
  119.     
  120.     If theCell is NULL, nothing is done and NULL is returned.
  121.     */
  122.     
  123.     
  124. void *cmAppendListCell(const void *theList, const void *theCell);
  125.     /*
  126.     This function is the same as a cmInsertAfterListCell(theList, theCell, NULL), i.e., 
  127.     theCell is appended to the end of the list.  The function returns the input inserted
  128.     cell pointer as its result.
  129.     
  130.     If theCell is NULL, nothing is done and NULL is returned.
  131.     */
  132.     
  133.     
  134. void *cmDeleteListCell(const void *theList, const void *theCell);
  135.     /*
  136.     This function removes the specified cell (theCell) from a list whose header is pointed
  137.     to by theList.  It is up to the caller to free the memory occupied by the cell.  Here
  138.   it is simply "jump out" of the list link structure.  The input cell pointer (theCell) is
  139.   returned as the function result.
  140.  
  141.     If theCell is NULL, nothing is done and NULL is returned.
  142.     */
  143.     
  144.     
  145. #if LISTMACROS
  146. #define cmGetNextListCell(currCell) ((void *)(((ListLinksPtr)(currCell))->next))
  147. #else
  148. void *cmGetNextListCell(void *currCell);
  149.     /*
  150.   Given a pointer to a list cell, this function returns the pointer to the next cell on
  151.   the list or NULL if there is no next cell.
  152.  
  153.   NULL is also returned if the input cell pointer is NULL.
  154.     */
  155. #endif
  156.  
  157.     
  158. #if LISTMACROS
  159. #define cmGetPrevListCell(currCell) ((void *)(((ListLinksPtr)(currCell))->prev))
  160. #else
  161. void *cmGetPrevListCell(void *currCell);
  162.     /*
  163.   Given a pointer to a list cell, this function returns the pointer to the previous cell
  164.   on the list or NULL if there is no previous cell.
  165.   
  166.   NULL is also returned if the input cell pointer is NULL.
  167.     */
  168. #endif
  169.     
  170.     
  171. #if LISTMACROS
  172. #define cmCountListCells(theList) ((long)(((ListHdrPtr)(theList))->nbrOfCells))
  173. #else
  174. CM_ULONG cmCountListCells(const void *theList);
  175.     /*
  176.   This function can be used to determine the number of cells in a list.  0 is returned if
  177.   the list is currently empty. It is assumed that the list has been previously initialized
  178.   by cmInitList().
  179.     */
  180. #endif
  181.     
  182.     
  183. #if LISTMACROS
  184. #define cmIsEmptyList(theList) (((ListHdrPtr)(theList))->nbrOfCells == 0)
  185. #else
  186. CMBoolean cmIsEmptyList(const void *theList);
  187.     /*
  188.   This function returns true if the specified list is empty (i.e., contains no cells) and
  189.   false otherwise (i.e., contains cells).
  190.     */
  191. #endif
  192.  
  193.  
  194. #if LISTMACROS
  195. #define cmGetListHead(theList) ((void *)(((ListHdrPtr)(theList))->head))
  196. #else
  197. void *cmGetListHead(const void *theList);
  198.     /*
  199.     Return the pointer to the head of a list.
  200.     */
  201. #endif
  202.     
  203.  
  204. #if LISTMACROS
  205. #define cmGetListTail(theList) ((void *)(((ListHdrPtr)(theList))->tail))
  206. #else
  207. void *cmGetListTail(const void *theList);
  208.     /*
  209.     Return the pointer to the tail of a list.
  210.     */
  211. #endif
  212.  
  213.  
  214. #if LISTMACROS
  215. #define cmNullListLinks(theCell) (((ListLinksPtr)(theCell))->prev = ((ListLinksPtr)(theCell))->next = NULL, (void *)(theCell))
  216. #else
  217. void *cmNullListLinks(void *theCell);
  218.     /*
  219.     Force the links in a list cell to NULL.  This is generally done as a safety measure
  220.     after a cell is allocated.  If the cell finds its way into a linked list then most list
  221.     walkers will be happy with NULL list links if they see them.  "Bad" cells like these
  222.     could arise from error conditions which may be seen during a cleanup.
  223.     */
  224. #endif
  225.     
  226.     
  227. void *cmGetNthListCell(const void *theList, const CM_ULONG n);
  228.     /*
  229.   This function returns a pointer to the N'th cell (counting from 1) on a list whose
  230.   header is pointed to by theList.  NULL is returned if there is no N'th list item.
  231.     */
  232.     
  233.     
  234. void *cmInsertBeforeNthListCell(const void *theList, const void *theCell, const CM_ULONG n);
  235.     /*
  236.     This function inserts the specified cell (theCell) before the N'th cell (counting from
  237.     1) on the list whose header is pointed to by theList.  The function returns the input
  238.     inserted cell pointer as its result.
  239.     
  240.     Nothing is inserted and NULL is returned if if there is no N'th list item or theCell is
  241.     NULL.
  242.     */
  243.     
  244.     
  245. void *cmInsertAfterNthListCell(const void *theList, const void *theCell, const CM_ULONG n);    
  246.     /*
  247.     This function inserts the specified cell (theCell) after the N'th cell (counting from
  248.     1) on the list whose header is pointed to by theList.  The function returns the input
  249.     inserted cell pointer as its result.
  250.     
  251.     Nothing is inserted and NULL is returned if if there is no N'th list item or theCell is
  252.     NULL.
  253.     */
  254.  
  255.  
  256. void *cmInsertNthListCell(const void *theList, const void *theCell, const CM_ULONG n);
  257.     /*
  258.     This function makes the specified cell (theCell) the N'th cell (counting from 1) on the
  259.     list whose header is pointed to by theList.  The function returns the input inserted
  260.     cell pointer as its result.
  261.     
  262.     Nothing is inserted and NULL is returned or if N is specified as 0 or 1 greater than
  263.     the total number of cells currently on the list.  NULL is also returned if theCell is
  264.     NULL.
  265.     
  266.     If N is specified a 1 greater than the total number of cells currently on the list then
  267.     the new cell is APPENDED to the end of the list.  If N is anything less, the new cell
  268.     is inserted BEFORE the old N'th cell.  Thus the new cell becomes the N'th cell.
  269.     */
  270.     
  271.     
  272. CM_ULONG cmGetCellPosition(const void *theList, const void *theCell);
  273.     /*
  274.     This function returns the position index, 1 to N, of the cell (theCell) in the list whose
  275.     header is pointed to by theList.  The function returns 0 if theCell cannot be found in 
  276.     theList.
  277.     */
  278.     
  279.  
  280. void cmForEachListCell(const void *theList, CMRefCon refCon,
  281.                                               void (*action)(void *cell, CMRefCon refCon));
  282.     /*
  283.     Do (call) the specified action for each cell on the specified list whose header is 
  284.     pointed to by theList. This routine calls (*action)() on each cell along with a "refCon"
  285.     which the caller can use as a communication facility to convey additional info to the
  286.     action routine.  The pointer to the cell is passed to the action routine.
  287.     */
  288.     
  289.     
  290. void cmFreeAllListCells(const void *theList, struct SessionGlobalData *sessionData);
  291.     /*
  292.     This routine removes (i.e., free()s) all the cells from the specified list.  The list
  293.     header is reinitialized.  Because it uses the memory deallocator it need the global data
  294.     session pointer.
  295.     */
  296.     
  297.  
  298.                                                           CM_END_CFUNCTIONS
  299. #endif
  300.